//  INotification.hpp
//  PureMVC_C++
//
//  PureMVC Port to C++ by Tang Khai Phuong <phuong.tang@puremvc.org>
//  PureMVC - Copyright(c) 2006-2011 Futurescale, Inc., Some rights reserved.
//  Your reuse is governed by the Creative Commons Attribution 3.0 License
//
//  中文注释：
//  INotification接口定义了PureMVC框架中的通知机制。
//  通知用于在应用程序的不同组件之间传递消息，实现松耦合的通信。
//  它遵循发布/订阅模式，允许组件之间无需直接引用即可通信。
//

#if !defined(__PUREMVC_INTERFACES_INOTIFICATION_HPP__)
#define __PUREMVC_INTERFACES_INOTIFICATION_HPP__

// STL include
#include <string>
// PureMVC include
#if !defined(__PUREMVC_HPP__)
#define __PUREMVC_INCLUDE__
#include "../PureMVC.hpp"
#endif /* __PUREMVC_HPP__ */

namespace PureMVC
{
    namespace Interfaces
    {
        /**
             * PureMVC通知的接口定义
             * The interface definition for a PureMVC Notification.
             *
             * <P>
             * PureMVC不依赖于底层事件模型，如Flash提供的模型，
             * 且ActionScript 3没有固有的事件模型。
             * PureMVC does not rely upon underlying event models such
             * as the one provided with Flash, and ActionScript 3 does
             * not have an inherent event model.</P>
             *
             * <P>
             * PureMVC中实现的观察者模式用于支持应用程序与MVC三元组之间的事件驱动通信。
             * The Observer Pattern as implemented within PureMVC exists
             * to support event-driven communication between the
             * application and the actors of the MVC triad.</P>
             *
             * <P>
             * 通知并不意味着要替换Flex/Flash/AIR中的事件。
             * 通常，<code>IMediator</code>实现者在其视图组件上放置事件监听器，
             * 然后以通常的方式处理它们。这可能导致广播<code>Notification</code>来
             * 触发<code>ICommand</code>或与其他<code>IMediator</code>通信。
             * <code>IProxy</code>和<code>ICommand</code>实例通过广播<code>INotification</code>
             * 相互通信并与<code>IMediator</code>通信。
             * Notifications are not meant to be a replacement for Events
             * in Flex/Flash/AIR. Generally, <code>IMediator</code> implementors
             * place event listeners on their view components, which they
             * then handle in the usual way. This may lead to the broadcast of <code>Notification</code>s to
             * trigger <code>ICommand</code>s or to communicate with other <code>IMediators</code>. <code>IProxy</code> and <code>ICommand</code>
             * instances communicate with each other and <code>IMediator</code>s
             * by broadcasting <code>INotification</code>s.</P>
             *
             * <P>
             * Flash <code>Event</code>和PureMVC <code>Notification</code>之间的一个关键区别是，
             * <code>Event</code>遵循'责任链'模式，在显示层次结构中'bubbling'，
             * 直到某个父组件处理<code>Event</code>，而PureMVC <code>Notification</code>
             * 遵循'发布/订阅'模式。PureMVC类不需要以父子关系相互关联
             * 即可使用<code>Notification</code>相互通信。
             * A key difference between Flash <code>Event</code>s and PureMVC
             * <code>Notification</code>s is that <code>Event</code>s follow the
             * 'Chain of Responsibility' pattern, 'bubbling' up the display hierarchy
             * until some parent component handles the <code>Event</code>, while
             * PureMVC <code>Notification</code>s follow a 'Publish/Subscribe'
             * pattern. PureMVC classes need not be related to each other in a
             * parent/child relationship in order to communicate with one another
             * using <code>Notification</code>s.
             *
             * @see Interfaces/IView.hpp PureMVC::Interfaces::IView
             * @see Interfaces/IObserver.hpp PureMVC::Interfaces::IObserver
             */

            struct PUREMVC_API INotification
        {
            /**
                 * 获取<code>INotification</code>实例的名称
                 * Get the name of the <code>INotification</code> instance.
                 * 没有setter，只能通过构造函数设置
                 * No setter, should be set by constructor only
                 * @return <code>INotification</code>实例的名称
                 */
                virtual std::string const& getName(void) const = 0;

            /**
                 * 设置<code>INotification</code>实例的主体内容
                 * Set the body of the <code>INotification</code> instance
                 * @param body 要设置的主体内容指针
                 */
                virtual void setBody(void const* body) = 0;

            /**
                 * 获取<code>INotification</code>实例的主体内容
                 * Get the body of the <code>INotification</code> instance
                 * @return 主体内容的指针
                 */
                virtual void const* getBody(void) const = 0;

            /**
                 * 设置<code>INotification</code>实例的类型
                 * Set the type of the <code>INotification</code> instance
                 * @param type 要设置的类型字符串
                 */
                virtual void setType(std::string const& type) = 0;

            /**
                 * 获取<code>INotification</code>实例的类型
                 * Get the type of the <code>INotification</code> instance
                 * @return 类型字符串
                 */
                virtual std::string const& getType(void) const = 0;

            /**
                 * 获取<code>INotification</code>实例的字符串表示
                 * Get the string representation of the <code>INotification</code> instance
                 * @return 实例的字符串表示
                 */
                virtual std::string toString(void) const = 0;

            /**
                 * 获取<code>INotification</code>实例的字符串表示（将结果存入参数）
                 * Get the string representation of the <code>INotification</code> instance
                 * @param arg 用于存储结果的字符串引用
                 */
                virtual void toString(std::string& arg) const = 0;

            /**
                 * 虚析构函数
                 * Virtual destructor.
                 */
                virtual ~INotification(void);
        };
    }
}

#endif /* __PUREMVC_INTERFACES_INOTIFICATION_HPP__ */
